Developer Documentation

QuickTime 4 API Documentation

QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top | Next |

Configuring Sequence Grabber Components

SGSetDataRef

The SGSetDataRef function specifies the destination data reference for a record operation.

pascal ComponentResult SGSetDataRef (
                     SeqGrabComponent s,
                     Handle dataRef,
                     OSType dataRefType,
                     long whereFlags);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
dataRef
Contains a handle to the information that identifies the destination container.
dataRefType
Specifies the type of data reference. If the data reference is an alias, you must set the parameter to rAliasType ( 'alis' ), indicating that the reference is an alias.
whereFlags
Contains flags that control the record operation. You must set either the seqGrabToDisk flag or the seqGrabToMemory flag to 1 (set unused flags to 0):
seqGrabToDisk
Instructs the sequence grabber component to write the recorded data to a QuickTime movie in the container specified by the dataRef parameter. If you set this flag to 1, the sequence grabber writes the data to the container as the data is recorded. Set this flag to 0 if you set the seqGrabToMemory flag to 1. Only one of these two flags may be set to 1.
seqGrabToMemory
Instructs the sequence grabber component to store the recorded data in memory until the recording process is complete. The sequence grabber then writes the recorded data to the container specified by the dataRef parameter. This technique provides better performance than recording directly to the container, but limits the amount of data you can record. Set this flag to 1 to record to memory. Set this flag to 0 if you set the seqGrabToDisk flag to 1. Only one of these two flags may be set to 1.
seqGrabDontUseTempMemory
Prevents the sequence grabber component from using temporary memory during the record operation. By default, the sequence grabber component and its channel components use as much temporary memory as necessary to perform the record operation. Set this flag to 1 to prevent the sequence grabber component and its channel components from using temporary memory.
seqGrabAppendToFile
Directs the sequence grabber component to add the recorded data to the data fork of the container specified by the dataRef parameter. By default, the sequence grabber component deletes the container and creates a new file containing one movie and the corresponding movie resource. Set this flag to 1 to cause the sequence grabber component to append the recorded data to the data fork of the container and create a new movie resource in that file.
seqGrabDontAddMovieResource
Prevents the sequence grabber component from adding the new movie resource to the container specified by the dataRef parameter. By default, the sequence grabber component creates a new movie resource and adds that resource to the container. Set this flag to 1 to prevent the sequence grabber component from adding the movie resource to the container. You are then responsible for adding the resource to a file, if you so desire.
seqGrabDontMakeMovie
Prevents the sequence grabber component from creating a movie. By default, the sequence grabber component creates a new movie resource and adds the captured data to that movie. If you set this flag to 1, the sequence grabber still calls your data function, but does not write any data to the movie file.
seqGrabDataProcIsInterruptSafe
Specifies that your data function is interrupt-safe, and may be called at interrupt time. This allows the sequence grabber component to present the captured data as soon as possible. Note that not all sequence grabber channel components may use this feature. It is currently supported only by sequence grabber sound channels.

DISCUSSION

The SGSetDataRef function allows you to specify the destination for a record operation using a data reference, and to specify other options that govern the operation. This function is similar to the SGSetDataOutput function, and provides you an alternative way to specify the destination.

If you are performing a preview operation, you do not need to use the SGSetDataRef function.

RESULT CODES

notEnoughMemoryToGrab
-9403 Insufficient memory for operation
notEnoughDiskSpaceToGrab
-9404 Insufficient disk space for operation

SGGetDataRef

The SGGetDataRef function allows you to determine the data reference that is currently assigned to a sequence grabber component and the control flags that would govern a record operation.

pascal ComponentResult SGGetDataRef (
                     SeqGrabComponent s,
                     Handle *dataRef,
                     OSType *dataRefType,
                     long *whereFlags);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
dataRef
Contains a pointer to a handle that is to receive the information that identifies the destination container.
dataRefType
Specifies a pointer to a field that is to receive the type of data reference.
whereFlags
Contains a pointer to a long integer that is to receive flags that control the record operation. The following flags are defined (unused flags are set to 0):
seqGrabToDisk
Instructs the sequence grabber component to write the recorded data to a QuickTime movie in the container specified by the dataRef parameter. If this flag is set to 1, the sequence grabber writes the data to the container as the data is recorded.
seqGrabToMemory
Instructs the sequence grabber component to store the recorded data in memory until the recording process is complete. The sequence grabber then writes the recorded data to the container specified by the dataRef parameter. This technique provides better performance than recording directly to the movie file, but limits the amount of data you can record. If this flag is set to 1, the sequence grabber component is recording to memory.
seqGrabDontUseTempMemory
Prevents the sequence grabber component from using temporary memory during the record operation. By default, the sequence grabber component and its channel components use as much temporary memory as necessary to perform the record operation. If this flag is set to 1, the sequence grabber component and its channel components do not use temporary memory.
seqGrabAppendToFile
Directs the sequence grabber component to add the recorded data to the data fork of the container specified by the dataRef parameter. By default, the sequence grabber component deletes the container and creates a new file containing one movie and its movie resource. If this flag is set to 1, the sequence grabber component appends the recorded data to the data fork of the container and creates a new movie resource in that file.
seqGrabDontAddMovieResource
Prevents the sequence grabber component from adding the new movie resource to the container specified by the dataRef parameter. By default, the sequence grabber component creates a new movie resource and adds that resource to the container. If this flag is set to 1, the sequence grabber component does not add the movie resource to the container. You are then responsible for adding the resource to a file, if you so desire.
seqGrabDontMakeMovie
Prevents the sequence grabber component from creating a movie. By default, the sequence grabber component creates a new movie resource and adds the captured data to that movie. If this flag is set to 1, the sequence grabber still calls your data function, but does not write any data to the container.
seqGrabDataProcIsInterruptSafe
Specifies that your data function is interrupt-safe, and may be called at interrupt time. This allows the sequence grabber component to present the captured data as soon as possible. Note that not all sequence grabber channel components may use this feature.

DISCUSSION

The SGGetDataRef function allows you to determine the data reference that is currently assigned to a sequence grabber component and the control flags that would govern a record operation.

You set these characteristics by calling SGSetDataRef . If you have not set these characteristics before calling the SGGetDataRef function, the returned data is meaningless.

SGSettingsDialog

The SGSettingsDialog function has a new flag value that you can pass in the flags parameter. Previously, you could only set this parameter to 0. Pass the new flag, seqGrabSettingsPreviewOnly , to indicate that you want to display only panels that make sense for previewing. In particular, the video compression will not be displayed. Use this flag for applications that allow a live video signal to be viewed but not captured.

flags
Either set this to 0 or to seqGrabSettingsPreviewOnly . The function supports the following flag value:
seqGrabSettingsPreviewOnly
Use this value if you want to view but not capture a live video signal. Otherwise, set the flags parameter to 0.
© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |